home *** CD-ROM | disk | FTP | other *** search
/ EuroCD 3 / EuroCD 3.iso / Communication / System-X / SX / Developer / AEDoor.doc next >
Encoding:
Text File  |  1998-06-24  |  13.9 KB  |  540 lines
  1. TABLE OF CONTENTS
  2.  
  3. AEDoor.library/CreateComm
  4. AEDoor.library/DeleteComm
  5. AEDoor.library/SendCmd
  6. AEDoor.library/SendStrCmd
  7. AEDoor.library/SendDataCmd
  8. AEDoor.library/SendStrDataCmd
  9. AEDoor.library/GetData
  10. AEDoor.library/GetString
  11. AEDoor.library/Prompt
  12. AEDoor.library/WriteStr
  13. AEDoor.library/ShowGFile
  14. AEDoor.library/ShowFile
  15. AEDoor.library/SetDT
  16. AEDoor.library/GetDT
  17. AEDoor.library/GetStr
  18. AEDoor.library/CopyStr
  19. AEDoor.library/HotKey
  20. AEDoor.library/PreCreateComm
  21. AEDoor.library/PostDeleteComm
  22. AEDoor.library/CreateComm
  23.  
  24.    NAME
  25.     CreateComm - Create a door communication channel (Changed in V2)
  26.  
  27.    SYNOPSIS
  28.     dif = CreateComm(node)
  29.      D0               D0
  30.  
  31.     struct DIFace *CreateComm(ULONG);
  32.  
  33.     ---CHANGED IN V2.0---
  34.     dif = CreateComm()
  35.      D0
  36.  
  37.    CHANGED!
  38.     The V2.0 routine is still 100% compatible with the V1.x function, but
  39.     now it finds the node number itself by looking it up in the argument
  40.     string passed to the door. This change was necessary since there was
  41.     no other way to make this 32 node compatible. Anyway, you won't notice
  42.     anything about this! But PLEASE make sure that you ask exec for V2 of
  43.     this library if you don't pass the node number anymore!!!!
  44.     The interfaces for C, E, Pascal still require a parameter to be passed
  45.     to this function, but the lib routine doesn't use the parameter
  46.     anymore.
  47.  
  48.    FUNCTION
  49.         This function is normally called at the start of a door. It allocates
  50.         and initializes all the structures it needs to communicate with amix.
  51.         If all went well, then the JH_REGISTER command is send to amix to
  52.         notify express that the door is ready.
  53.  
  54.    NOTE
  55.         When there is not enough memory to allocate a structure, then the
  56.         function will delay for 1 second and will try again, until it can
  57.         allocate it's resources. This is done because there is NO way to tell
  58.         amix that we're out of memory (maybe /X 3.0 will have this fixed?!)
  59.         The waiting is done by the dos.library call _LVODelay(), this way
  60.         precious CPU Time is spared!
  61.  
  62.    EXAMPLE
  63.         CreateComm(argv[1][0]);
  64.  
  65.    INPUTS
  66.     node - The ASCII (!) value of the node number. This value is passed to
  67.                the door by amix as a parameter. (OBSOLETE IN V2.0)
  68.  
  69.    RESULT
  70.         dif - Ptr to an initialized DIFace structure
  71.  
  72.    SEE ALSO
  73.     DeleteComm
  74.  
  75. AEDoor.library/DeleteComm
  76.  
  77.    NAME
  78.     DeleteComm - Delete a door communication channel
  79.  
  80.    SYNOPSIS
  81.     DeleteComm(dif)
  82.                  A1
  83.  
  84.     void DeleteComm(struct DIFace *);
  85.  
  86.    FUNCTION
  87.         You *MUST* call this function to remove the communication channel made
  88.         by the CreateComm() call. This function will take care of freeing all
  89.         allocated memory and telling amix the door finnished it's job (it will
  90.         send a JH_SHUTDOWN to amix)
  91.  
  92.    NOTE
  93.         This call will close the comm channel, so you won't be able to send
  94.         cmd's to express anymore, BUT the door can still do other tasks. So it
  95.         is NOT necessary to quit right after doing a DeleteComm() call!!
  96.  
  97.         !!IMPORTANT!!
  98.         It is *NOT* possible to re-initialise the communication channel with
  99.         express after doing a DeleteComm()
  100.  
  101.    EXAMPLE
  102.         DeleteComm(dif);
  103.  
  104.    INPUTS
  105.     dif - A pointer to the DIFace structure returned by CreateComm()
  106.  
  107.    SEE ALSO
  108.     CreateComm
  109.  
  110. AEDoor.library/SendCmd
  111.  
  112.    NAME
  113.         SendCmd -- Send a door command to ami express
  114.  
  115.    SYNOPSIS
  116.         SendCmd( dif, command )
  117.                  A1     D0
  118.  
  119.         void SendCmd(struct DIFace *,ULONG)
  120.  
  121.    FUNCTION
  122.         This function will send a simple command to the ami express
  123.         AEDoorPort and will wait for express to reply to the message.
  124.  
  125.    INPUTS
  126.         command - Function Identifier
  127.         dif     - Ptr to DIFace structure
  128.  
  129.    SEE ALSO
  130.     <amix/amix.i>
  131.  
  132. AEDoor.library/SendStrCmd
  133.  
  134.    NAME
  135.         SendStrCmd -- Send a string door command to ami express (V2)
  136.  
  137.    SYNOPSIS
  138.         SendStrCmd( dif, command, string )
  139.                      A1    D0      A0
  140.  
  141.         void SendStrCmd(struct DIFace *,ULONG,char *)
  142.  
  143.    FUNCTION
  144.         This function will send a string command to the ami express
  145.         AEDoorPort and will wait for express to reply to the message.
  146.         The string in A0 will first be copied into the JHM_String field
  147.         and then the function SendCmd() will be called.
  148.     V2: Strings larger than 200 chars will be chopped
  149.  
  150.    INPUTS
  151.         command - Function Identifier
  152.         string  - Ptr to NULL terminate string
  153.         dif     - Ptr to DIFace structure
  154.  
  155.    SEE ALSO
  156.     <amix/amix.i>
  157.  
  158. AEDoor.library/SendDataCmd
  159.  
  160.    NAME
  161.         SendDataCmd -- Send a data door command to ami express
  162.  
  163.    SYNOPSIS
  164.         SendDataCmd( dif, command, data )
  165.                       A1    D0      D1
  166.  
  167.         void SendDataCmd(struct DIFace *,ULONG,ULONG)
  168.  
  169.    FUNCTION
  170.         This function will send a data command to the ami express AEDoorPort
  171.         and will wait for express to reply to the message. The data in D1
  172.         will first be copied into the JHM_Data field and then the function
  173.         SendCmd() will be called.
  174.  
  175.    INPUTS
  176.         command - Function Identifier
  177.         data    - Data 
  178.         dif     - Ptr to DIFace structure
  179.  
  180.    SEE ALSO
  181.     <amix/amix.i>
  182.  
  183. AEDoor.library/SendStrDataCmd
  184.  
  185.    NAME
  186.         SendStrDataCmd -- Send a string & data door command to ami express
  187.                                       (V2)
  188.  
  189.    SYNOPSIS
  190.         SendStrDataCmd( dif, command, string, data )
  191.                         A1     D0      A0      D1
  192.  
  193.         void SendStrDataCmd(struct DIFace *,ULONG,char *,ULONG)
  194.  
  195.    FUNCTION
  196.         This function will send a string & data command to the ami express
  197.         AEDoorPort and will wait for express to reply to the message.
  198.         The string in A0 will first be copied into the JHM_String field
  199.         and the data in D1 will be copied to the JHM_Data field after that
  200.         the function SendCmd() will be called.
  201.     V2: Strings larger than 200 chars will be chopped
  202.  
  203.    INPUTS
  204.         command - Function Identifier
  205.         data    - Data to be send to amix
  206.         string  - Ptr to NULL terminate string
  207.         dif     - Ptr to DIFace structure
  208.  
  209.    SEE ALSO
  210.     <amix/amix.i>
  211.  
  212. AEDoor.library/GetData
  213.  
  214.    NAME
  215.         GetData -- Get a pointer to the JHM_Data field
  216.  
  217.    SYNOPSIS
  218.         pdata = GetData( dif )
  219.          D0              A1
  220.  
  221.         int *GetData(struct DIFace *)
  222.  
  223.    FUNCTION
  224.         Get the address of the JHM_Data field. Please use this function,
  225.         instead of trying to find the field yourself. This way we will keep
  226.         the doors compatible with future revisions of ami express!
  227.  
  228.    INPUTS
  229.         dif - Ptr to DIFace structure
  230.  
  231.    RESULT
  232.         pdata - Ptr to JHM_Data field
  233.  
  234.    NOTE
  235.         *OBSOLETE* as of V1.4 of AEDoor.library, since now the ptr is kept
  236.         in the DIFace structure (dif_Data). The function will still work tho,
  237.         but it's faster to get the address directly from the dif_Data field!
  238.  
  239. AEDoor.library/GetString
  240.  
  241.    NAME
  242.         GetString -- Get a pointer to the JHM_String field
  243.  
  244.    SYNOPSIS
  245.         pstring = GetString( dif )
  246.            D0                A1
  247.  
  248.         char *GetString(struct DIFace *)
  249.  
  250.    FUNCTION
  251.         Get the address of the JHM_String field. Please use this function,
  252.         instead of trying to find the field yourself. This way we will keep
  253.         the doors compatible with future revisions of ami express!
  254.  
  255.    INPUTS
  256.         dif - Ptr to DIFace structure
  257.  
  258.    RESULT
  259.         pstring - Ptr to JHM_String field
  260.  
  261.    NOTE
  262.         *OBSOLETE* as of V1.4 of AEDoor.library, since now the ptr is kept
  263.         in the DIFace structure (dif_String). The function will still work
  264.         tho, but it's faster to get the address directly from the dif_String
  265.         field!
  266.  
  267. AEDoor.library/Prompt
  268.  
  269.    NAME
  270.         Prompt -- Prompt the user for input, and limit the response size
  271.  
  272.    SYNOPSIS
  273.         pstring = Prompt( dif, length, pstring )
  274.            D0             A1     D1      A0
  275.  
  276.         char *Prompt(struct DIFace *,ULONG, char *)
  277.  
  278.    FUNCTION
  279.     The string is send to amix prompting the user to enter something. The
  280.     size of the input field is limited by the length variable.
  281.  
  282.    INPUTS
  283.         dif    - Ptr to DIFace structure
  284.     length    - max number of chars the user can enter
  285.     pstring - prompt string
  286.  
  287.    RESULT
  288.         pstring - Ptr to JHM_String field or
  289.           NULL if Lost Carrier
  290.    NOTE
  291.     For the convinience of asm programmers, the Z flag will be set when
  292.     there was a loss of carrier
  293.  
  294. AEDoor.library/WriteStr
  295.  
  296.    NAME
  297.         WriteStr -- Output a string to the user (V2)
  298.  
  299.    SYNOPSIS
  300.         WriteStr( dif, string, flags )
  301.                   A1     A0     D1
  302.  
  303.         void WriteStr(struct DIFace *,char *,ULONG)
  304.  
  305.    FUNCTION
  306.     Output the string to the user, adding a LF depending on the status
  307.     of the feed variable
  308.  
  309.    UPDATE V2 INFO
  310.     The parameter feed has been replaced by flags, but this function is
  311.     still 100% compatible with the V1 function.
  312.  
  313.    INPUTS
  314.         dif     - Ptr to DIFace structure
  315.     string    - Ptr to string to output
  316.     flags    - LF  : Print a LineFeed after the text
  317.           SAFE: Allow strings larger than 200 chars to be printed
  318.  
  319.    NOTE
  320.     The flags are:
  321.         WSF_LF   = LineFeed FLAG            (= 1)
  322.         WSB_LF   = LineFeed-flag bit number (= 0)
  323.         WSF_SAFE = Safe >200 strings        (= 2)
  324.         WSB_SAFE = Safe-flag bit number     (= 1)
  325.  
  326.     Or to put it simpler: WSF_... = 1<<WSB_...
  327.  
  328. AEDoor.library/ShowGFile
  329.  
  330.    NAME
  331.         ShowGFile -- Show an /X file
  332.  
  333.    SYNOPSIS
  334.         ShowGFile( dif, file )
  335.                    A1    A0
  336.  
  337.         void ShowGFile(struct DIFace *,char *)
  338.  
  339.    FUNCTION
  340.     Show a file using the proper extension depending on the user's
  341.     settings. This is the standard routine that AmiX uses to display
  342.     the bulletins, menus, ...
  343.  
  344.    INPUTS
  345.         dif     - Ptr to DIFace structure
  346.     file    - Ptr to filename of file to show
  347.  
  348.  
  349. AEDoor.library/ShowFile
  350.  
  351.    NAME
  352.         ShowFile -- Show a file
  353.  
  354.    SYNOPSIS
  355.         ShowFile( dif, file )
  356.                   A1    A0
  357.  
  358.         void ShowFile(struct DIFace *,char *)
  359.  
  360.    FUNCTION
  361.     Show a file AS IS.
  362.  
  363.    INPUTS
  364.         dif     - Ptr to DIFace structure
  365.     file    - Ptr to filename of file to show
  366.  
  367.  
  368. AEDoor.library/SetDT
  369.  
  370.    NAME
  371.         SetDT -- Set Data
  372.  
  373.    SYNOPSIS
  374.         SetDT( dif, id, str)
  375.                 A1  D0  A0
  376.  
  377.         void SetDT(struct DIFace *,ULONG,char *)
  378.  
  379.    FUNCTION
  380.     Set/change one of the many data fields available in AmiX
  381.  
  382.    INPUTS
  383.         dif     - Ptr to DIFace structure
  384.     id    - Data Identifier
  385.     str    - Ptr to a string that holds the new info
  386.  
  387.    SEE ALSO
  388.     <amix/amix.i>
  389.  
  390.  
  391. AEDoor.library/GetDT
  392.  
  393.    NAME
  394.         GetDT -- Get Data
  395.  
  396.    SYNOPSIS
  397.         GetDT( dif, id, str)
  398.                 A1  D0  A0
  399.  
  400.         void GetDT(struct DIFace *,ULONG,char *)
  401.  
  402.    FUNCTION
  403.     Get one of the many data fields available in AmiX
  404.  
  405.    INPUTS
  406.         dif     - Ptr to DIFace structure
  407.     id    - Data Identifier
  408.     str    - Ptr to a string that contains additional information
  409.           (if required, else set to NULL)
  410.  
  411.    SEE ALSO
  412.     <amix/amix.i>
  413.  
  414.  
  415. AEDoor.library/GetStr
  416.  
  417.    NAME
  418.         GetStr -- Get input from the user, supply a default setting
  419.  
  420.    SYNOPSIS
  421.         pstring = GetStr( dif, length, defstr )
  422.            D0             A1     D1      A0
  423.  
  424.         char *GetStr(struct DIFace *,ULONG, char *)
  425.  
  426.    FUNCTION
  427.     The user is asked to enter something, but before that, the input
  428.     buffer is filled with the default string.
  429.  
  430.    INPUTS
  431.         dif    - Ptr to DIFace structure
  432.     length    - max number of chars the user can enter
  433.     defstr    - default string
  434.  
  435.    RESULT
  436.         pstring - Ptr to JHM_String field or
  437.           NULL if Lost Carrier
  438.  
  439.    NOTE
  440.     For the convinience of asm programmers, the Z flag will be set when
  441.     there was a loss of carrier
  442.  
  443.  
  444. AEDoor.library/CopyStr
  445.  
  446.    NAME
  447.         CopyStr -- Get a fast copy of the JHM_String field
  448.  
  449.    SYNOPSIS
  450.         CopyStr( dif, buffer )
  451.                   A1    A0
  452.  
  453.         void CopyStr(struct DIFace *, char *)
  454.  
  455.    FUNCTION
  456.     The JHM_String is copied to the buffer, you must make a copy of the
  457.     JHM_String because if you use another function, the contents of the
  458.     JHM_String will probably change.
  459.  
  460.    INPUTS
  461.         dif    - Ptr to DIFace structure
  462.     buffer    - Ptr to a buffer big enough to contain a copy of the
  463.           JHM_String field
  464.  
  465.    NOTE
  466.     This routine doesn't check for anything, it just copies all the bytes
  467.     in the string entry until it reaches a NULL byte, so if the string is
  468.     not NULL terminated, ya can be damn sure it will damage some memory!
  469.  
  470.  
  471. AEDoor.library/HotKey
  472.  
  473.    NAME
  474.         HotKey -- Prompts a user and wait for him to press a key   (V11)
  475.  
  476.    SYNOPSIS
  477.         key = HotKey( dif, promptstr )
  478.         D0             A1     A0
  479.  
  480.         LONG HotKey(struct DIFace *, char *)
  481.  
  482.     FUNCTION
  483.         This function prompts the user with the given string , and waits
  484.         for a key to be pressed. ASCII code of pressed key is returned or
  485.     (LONG) -1 when a loss of carrier occured
  486.         You can provide a NULL value for promptstring.
  487.  
  488.    INPUTS
  489.         dif      - Ptr to DIFace structure
  490.     promptstr - Pointer to the string to be print when prompting.
  491.             (or NULL)
  492.  
  493.    RESULT
  494.         key - (LONG) returns ASCII code of pressed key or returns -1 if the
  495.               user lost carrier or if sysop wants to throw him off the board.
  496.  
  497.    NOTE
  498.     For the convinience of asm programmers, the N flag will be set when
  499.     there was a loss of carrier (so a simple BMI after the JSR will do)
  500.  
  501.    BUG FIX (V11)
  502.     When the entered character was negative ($80-$FF), the N flag was set
  503.     on return. This lead to asm doors misinterpreting this as a loss of
  504.     carrier!
  505.    BUG FIX (2.4)
  506.     Supplying a NULL pointer for the promptstr caused a harmless enforcer
  507.     hit.
  508.  
  509.    SPECIAL NOTE
  510.     In the C pragrams, the routine is renamed to Hotkey() because the
  511.     HotKey() function was already defined in another library!
  512.  
  513.  
  514. AEDoor.library/PreCreateComm
  515.  
  516.    NAME
  517.     PreCreateComm - PRIVATE FUNCTION!! Never use this one!! (V13)
  518.  
  519.    SYNOPSIS
  520.     NOT 4 YOUR EYES!
  521.  
  522.    FUNCTION
  523.     This function is used for the Multi Door support, and should never
  524.     be used by anyone!
  525.  
  526.  
  527. AEDoor.library/PostDeleteComm
  528.  
  529.    NAME
  530.     PostDeleteComm - PRIVATE FUNCTION!! Never use this one!! (V13)
  531.  
  532.    SYNOPSIS
  533.     NOT 4 YOUR EYES!
  534.  
  535.    FUNCTION
  536.     This function is used for the Multi Door support, and should never
  537.     be used by anyone!
  538.  
  539.                                 --- EOF ---
  540.